README LINUX

   1 -*-text-*---------------------------------------------------------------
   2 supercollider 3 for linux
   3 ------------------------------------------------------------------------
   4 $Id$
   5 ------------------------------------------------------------------------
   6
   7 ------------------------------------------------------------------------
   8 intro
   9 ------------------------------------------------------------------------
  10
  11 SuperCollider is a synthesis engine (scsynth) and programming language
  12 (sclang), originally Mac-based but now very widely used on Linux
  13 (since Stefan Kersten ported the code in 2003). SuperCollider is free
  14 software under the GPL - its main homepage is at
  15
  16    http://supercollider.sourceforge.net
  17
  18 to get further information on supercollider usage or development, you
  19 might consider subscribing to the mailing lists
  20
  21   http://www.beast.bham.ac.uk/research/sc_mailing_lists.shtml
  22
  23 ------------------------------------------------------------------------
  24 build requirements
  25 (most of these will be available in your linux distribution as packages )
  26 ------------------------------------------------------------------------
  27
  28  * gcc >= 3.0
  29    http://www.gnu.org/software/gcc/
  30    gcc versions < 3.0 are missing some required c++ features
  31
  32  * jack and libjack
  33    http://jackit.sourceforge.net/
  34    jack audio connection kit
  35
  36  * libsndfile >= 1.0
  37    http://www.mega-nerd.com/libsndfile/
  38    _the_ soundfile i/o library
  39
  40  * pkg-config >= 0.14.0
  41    http://www.freedesktop.org/software/pkgconfig/
  42    facilitates checking for installed packages when compiling from
  43    source
  44
  45  * scons >= 0.96
  46    http://www.scons.org/
  47    configuration and build tool based on python
  48
  49  * fftw >= 3.0
  50    http://www.fftw.org/
  51    fast FFT transform library (for frequency-domain analysis,
  52                                         phase-vocoder effects)
  53
  54 ------------------------------------------------------------------------
  55 build requirements (optional features)
  56 (most of these will be available in your linux distribution as packages )
  57 ------------------------------------------------------------------------
  58
  59  * alsa
  60    http://www.alsa-project.org/
  61    advanced linux sound architecture drivers and library, for sclang's
  62    MIDI interface
  63
  64  * libreadline >= 5
  65    http://savannah.gnu.org/projects/readline
  66    provides convenient CLI interface for sclang
  67    (if unavailable, set READLINE=0 as an argument to scons)
  68
  69  * libhowl (obsolete)
  70    http://www.porchdogsoft.com/products/howl/
  71    zeroconf service dicovery implementation
  72
  73  * libavahi-client
  74    http://www.avahi.org/
  75    a more powerful zeroconf service discovery implementation
  76
  77  * linux kernel >= 2.6
  78    http://www.kernel.org/
  79    for sclang's linux input device (LID) interface
  80
  81  * for scel: the Emacs interface see the README in the directory
  82    `editors/scel'
  83
  84  * for sced: the gedit interface see the README in the directory
  85    `editors/sced'
  86
  87  * for scvim: the vim interface see the README in the directory
  88    `editors/scvim'
  89
  90
  91 ------------------------------------------------------------------------
  92 build requirements (debian users)
  93 ------------------------------------------------------------------------
  94
  95 on debian (unstable) you can install the following packages and be set
  96 for building supercollider:
  97
  98    gcc
  99    libjack0.100.0-dev
 100    libsndfile1-dev
 101    libasound2-dev
 102    libavahi-client-dev
 103    libreadline6-dev
 104    libfftw3-dev
 105    pkg-config
 106    scons
 107
 108 ------------------------------------------------------------------------
 109 building
 110 ------------------------------------------------------------------------
 111
 112 building with scons is not really different from building with
 113 autoconf, automake and related tools.
 114
 115    $ scons -H
 116
 117 gives an overview of scons options.
 118
 119    $ scons -h
 120
 121 lists package specific options variables and their default values.
 122 (Note: some options allow to disable the dependencies on fftw and on
 123 libsndfile, but those dependencies should be considered compulsory for
 124 most standard setups since they provide much core sc functionality.)
 125
 126 options can be set on the command line
 127
 128    $ scons VARIABLE=VALUE
 129
 130 and are cached in a file called scache.conf (which can be edited with
 131 your favorite editor) for use in the next scons invocation.
 132
 133 in order to build the whole package, call scons without arguments
 134 (apart from option variables). in order to install the package, call
 135 scons with the `install' target:
 136
 137    $ scons install
 138
 139 any target (including `install') can be cleaned with the `-c' option
 140 to scons; note that cleaning the `install' target also removes locally
 141 built files.
 142
 143 The option SCEL installs the emacs editor. For the sced and scvim editors,
 144 please use the scons scripts in their respective directories (in editors/).
 145
 146 ------------------------------------------------------------------------
 147 Building a Debian package
 148 ------------------------------------------------------------------------
 149
 150 In our SVN we have debian packaging rules. These were designed on Ubuntu
 151 but we believe they should work on most common debian systems - please
 152 let us know if you have any issues with this way of building:
 153
 154   cd SuperCollider3    # (or wherever your SC source is)
 155   svn co https://supercollider.svn.sourceforge.net/svnroot/supercollider/packages/ubuntu/ debian
 156   debuild
 157
 158 Eventually, some .deb packages will be put in the parent folder, and can
 159 then be installed just like any other Debian package. For example:
 160
 161   dpkg -i ../supercollider*.deb
 162
 163 (Note: the packages supercollider-scel*.deb, supercollider-scvim*.deb,
 164 supercollider-sced*.deb, represent the different editor integrations:
 165 emacs, vim, gedit. You might not want to install all of those, but
 166 choose your preferred editor.)
 167
 168
 169 ------------------------------------------------------------------------
 170 running scsynth (standalone)
 171 ------------------------------------------------------------------------
 172
 173 run scsynth without options to get an option summary. don't forget to
 174 start jackd before trying to use scsynth. if you want to add
 175 directories to supercollider's search path or assign default jack
 176 ports, set up your environment as described below.
 177
 178 you can specify the number of jack input/output channels created with
 179 the options -i and -o, respectively.
 180
 181 the -H option can be used to specify a jack server to connect to and
 182 to set the jack client identifier. the format is either
 183
 184     <SERVER-NAME>:<CLIENT-NAME>
 185
 186 or just
 187
 188     <CLIENT-NAME>
 189
 190 when connecting to the default server.
 191
 192 ------------------------------------------------------------------------
 193 running sclang
 194 ------------------------------------------------------------------------
 195
 196 it is recommended to use sclang in combination with your preferred text
 197 editor out of emacs/vim/gedit. see the README files in `linux/*' for
 198 installation and usage. as an alternative you can simply run the
 199 `sclang' executable which will provide a readline-based interface.
 200
 201 sclang executes the startup file `~/.sclang.sc' after class library
 202 initialization. this file can contain statements to set up your
 203 supercollider environment, like setting default variables. an example can
 204 be found in `linux/examples/sclang.sc'.
 205
 206 you _have_ to have a directory `~/share/SuperCollider/'. This is where
 207 automatically a synthdefs directory is created. It is also the place
 208 to put Extensions to the class library, in a folder called Extensions.
 209
 210 the runtime directory is either the current working directory or the
 211 path specified with the `-d' option.
 212
 213 for advanced setups, sclang's compilation search path can be
 214 customized with a library configuration file. an example is provided
 215 in `linux/examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
 216 `~/.sclang.cfg'. This config file is only needed when you want to
 217 _exclude_ directories from the class library. Otherwise (so in most cases)
 218 it is not needed.
 219
 220 ------------------------------------------------------------------------
 221 environment
 222 ------------------------------------------------------------------------
 223
 224 the jack audio driver interface is configured based on various
 225 environment variables:
 226
 227  * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
 228    scsynth's inputs should connect to by default
 229
 230    $ export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
 231
 232    in order to connect the first ports of one jack client, it is possible
 233    to specify only the client name
 234
 235    $ export SC_JACK_DEFAULT_INPUTS="system"
 236
 237  * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
 238    scsynth's outputs should be connected to by default.
 239
 240    $ export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
 241
 242    in order to connect the first ports of one jack client, it is possible
 243    to specify only the client name
 244
 245    $ export SC_JACK_DEFAULT_OUTPUTS="system"
 246
 247 two additional environment variables substitute directories for the default
 248 search path for plugins and synth definitions, respectively. directory
 249 names are separated by ':' as in the unix PATH variable:
 250
 251  * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH
 252
 253    $ export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
 254
 255 ------------------------------------------------------------------------
 256 documentation
 257 ------------------------------------------------------------------------
 258
 259 apart from the sites listed above, some more documentation links ...
 260
 261 a wiki for supercollider, set up by julian rohrhuber, is at
 262
 263     http://swiki.hfbk-hamburg.de/MusicTechnology/6
 264
 265 linux specific information can be found at
 266
 267     http://swiki.hfbk-hamburg.de/MusicTechnology/478
 268
 269 ------------------------------------------------------------------------
 270 reporting bugs
 271 ------------------------------------------------------------------------
 272
 273 please report bugs either to the sc-users or sc-dev mailing lists.
 274
 275 ------------------------------------------------------------------------
 276 contributors to this document
 277 ------------------------------------------------------------------------
 278
 279 stefan kersten <sk AT k-hornz DOT de>
 280 andi pieper
 281 maurizio umberto puxeddu
 282 rohan drape
 283 mario lang
 284 john yates
 285 nescivi (marije baalman)
 286 dan stowell
 287
 288 ------------------------------------------------------------------------
 289 outro
 290 ------------------------------------------------------------------------
 291
 292 thanks to james mccartney, for making this great piece of audio
 293 software publically and freely available.
 294
 295 ------------------------------------------------------------------------
 296 eof
 297 ------------------------------------------------------------------------
 298